<HTML><HEAD><TITLE>call_c(+Function, ?Code)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">External Interface</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>call_c(+Function, ?Code)</H1>
Invoke the C function Function and unify its return code with Code.


<DL>
<DT><EM>Function</EM></DT>
<DD>Atom or structure
</DD>
<DT><EM>Code</EM></DT>
<DD>Variable, integer or structure
</DD>
</DL>
<H2>Description</H2>
   This predicate allows to call C functions directly from Prolog.  The
   arguments of Function are translated as follows:

<P>
  * integers and floats are passed directly

<P>
  * strings and atoms are passed as C strings

<P>
  * terms Name/Arity are interpreted as arrays and a pointer to the first
    array's element is passed

<P>
  * structures in the form ar(M, N, K) are interpreted as array elements
    and a pointer to this array element is passed.

<P>
   C numbers and strings are thus mapped directly on Prolog constants, C
   structures are mapped on Prolog arrays.  If Code is a variable or an
   integer, it will be unified with the (integer) return code of the
   function.  If the function return value is of another type, it must be
   specified in the Code as follows:

<P>
  * integer(Code) denotes an integer

<P>
  * float(Code) denotes a (double precision) floating point number

<P>
  * string(Code) denotes a string

<P>
   After Function finishes, Code is unified with its return code.  If
   Function is a system function and the return code is -1, the flag
   last_errno contains the errno value set by the command.  Function can
   have at most 10 arguments (floating-point arguments count as two).  Note
   that only functions linked with the current session can be called.
   Other functions can be dynamically linked using the load/1 predicate.
   The first time a function is called it takes longer because the system
   has to find the function in the symbol table of the binary.  Its address
   is remembered and thus next calls are faster.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>call_c(+, ?) is det
</UL>
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Function is not instantiated.
<DT><EM>(5) type error </EM>
<DD>Function is neither an atom nor a structure.
<DT><EM>(5) type error </EM>
<DD>An argument of Function has a type which cannot be    translated.
<DT><EM>(20) arithmetic exception </EM>
<DD>Arithmetic exception in the function or when converting a    single-precision float to a double.
<DT><EM>(31) arity limit exceeded </EM>
<DD>Arity of Function exceeds 10.
<DT><EM>(41) array or global variable does not exist </EM>
<DD>The array argument of Function does not exist.
<DT><EM>(211) External function does not exist </EM>
<DD>The specified C function does not exist.
</DL>
<H2>Examples</H2>
<PRE>
Success:
    [eclipse 16]: make_array(time(4), integer).

    yes.
    [eclipse 17]: call_c(gettimeofday(time/1, time(2)), X).

    X = 0
    yes.
    [eclipse 18]: getval(time(0), Sec1Jan70), getval(time(2), MinWest),
              getval(time(3), DstTime).

    Sec1Jan70 = 733148538
    MinWest = -60
    DstTime = 4
    yes.
    [eclipse 19]: call_c(ctime(time(0)), string(Date)).

    Date = "Fri Mar 26 13:22:18 1993\n"
    yes.
    [eclipse 20]: call_c(sinh(1.5), float(X)).
    External function does not exist in call_c(sinh(1.5), float(X))
    [eclipse 21]: load("-u _sinh -lm"), call_c(sinh(1.5), float(X)).

    X = 2.12927938
    yes.

Error:
      call_c(nofunc, X).                  (Error 211).
      call_c(getrusage(noarray/1, 0)      (Error 41).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/opsys/exec-2.html">exec / 2</A>, <A HREF="../../kernel/opsys/system-1.html">system / 1</A>
</BODY></HTML>
